package org.as3search.config {
	/*
	 * as3search - http://code.google.com/p/as3search
	 * Copyright (c) 2009-2010 by respective authors. All rights reserved.
	 *
	 * This library is free software; you can redistribute it and/or modify it under the
	 * terms of the GNU Lesser General Public License as published by the Free Software
	 * Foundation; either version 2.1 of the License, or (at your option) any later
	 * version.
	 *
	 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
	 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
	 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
	 *
	 * You should have received a copy of the GNU Lesser General Public License along
	 * with this library; if not, write to the Free Software Foundation, Inc.,
	 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
	 */
	
	import org.as3search.criteria.Criteria;
	import org.as3search.properties.PropertyResolver;
	import org.as3search.providers.SearchProvider;
	import org.as3search.providers.SearchProviderMapping;

	/**
	 * The <code>SearchConfiguration</code> interface is one of the core facets
	 * which make as3search work. Implementors are responsible for managing 
	 * <code>SearchProvider</code> mappings for resolution via <code>getSearchProvider()</code>,
	 * adding new mappings (<code>addSearchProvider()</code>), remove mappings
	 * (<code>removeSearchProvider()</code>), and the creation of <code>Criteria</code>
	 * instances for actually searching through objects (<code>createCriteria()</code>).
	 * <code>SearchConfiguration</code> implementors are also responsible for 
	 * defining a <code>PropertyResolver</code> to aid in conversion of string
	 * property names to values, as well as a fail-over provider for objects which
	 * do not have a <code>SearchProvider</code> mapped to their type. <br/><br/>
	 * If you wish to have a very customizable search experience, you should start with 
	 * implementing this interface and defining your very own search configuration.
	 * 
	 * @see org.as3search.config.SearchConfigurationAware
	 * @see org.as3search.config.AbstractSearchConfiguration
	 */
	public interface SearchConfiguration {
		/**
		 * Returns an appropriate <code>SearchProvider</code> for <code>value</code>.
		 * @param	value	An object or collection instance to lookup a <code>SearchProvider</code>
		 * 		for. If unable to find a provider, <code>failoverProvider</code> should be returned.
		 * @return Returns the best <code>SearchProvider</code> instance for <code>value</code>.
		 */
		function getSearchProvider(value:Object):SearchProvider;
		/**
		 * Adds a <code>SearchProvider</code> to this configuration. 
		 * @param	targetType	The <code>Class</code> of the target type to map to <code>providerType</code>.
		 * @param	providerType The <code>SearchProvider</code> class to map to <code>targetType</code>.
		 * @return Returns this object for method chaining.
		 * 
		 * @see org.as3search.providers.SearchProvider
		 * @see org.as3search.providers.SearchProviderMapping
		 */
		function addSearchProvider(targetType:Class, providerType:Class):SearchConfiguration;
		/**
		 * Removes a <code>SearchProvider</code> from this configuration.
		 * @param	targetType	The <code>Class</code> of the target which the provider is mapped to.
		 * 		(The key for the <code>SearchProvider</code>)
		 * @return Returns this object for method chaining.
		 * 
		 * @see org.as3search.providers.SearchProvider
		 * @see org.as3search.providers.SearchProviderMapping
		 */
		function removeSearchProvider(targetType:Class):SearchConfiguration;
		/**
		 * Creates a <code>Criteria</code> instance to search through <code>value</code> with. 
		 * @param	value	The object or collection to search through.
		 * @return Returns a new <code>Criteria</code> instance wrapping <code>value</code>.
		 * 
		 * @see org.as3search.criteria.Criteria
		 */
		function createCriteria(value:Object):Criteria;
		/**
		 * This configuration's <code>PropertyResolver</code> instance. This instance is
		 * used to resolve complex properties of objects to aid in searching for
		 * matching conditions by <code>Criteria</code> instances.
		 * 
		 * @see org.as3search.properties.PropertyResolver
		 */
		function get propertyResolver():PropertyResolver;
		function set propertyResolver(value:PropertyResolver):void;
		/**
		 * An <code>Array</code> of <code>SearchProviderMapping</code> implementations
		 * describing the matching of target types to provider types. 
		 * 
		 * @see org.as3search.providers.SearchProvider
		 * @see org.as3search.providers.SearchProviderMapping
		 */
		function set providers(value:Array):void;
		/**
		 * A <code>SearchProviderMapping</code> describing a <code>SearchProvider</code> to 
		 * be used when no appropriate provider can be found.
		 * 
		 * @see org.as3search.providers.SearchProvider
		 * @see org.as3search.providers.SearchProviderMapping
		 */
		function set failoverProvider(value:SearchProviderMapping):void;
	}
}